PICFIB Documentation V1.1a 1995.11.28 for PICFIB V1.1a from 1995.11.28 P I C F I B by A. Rosenberg (AR) DISCLAIMER: Don't hold me (AR) responsible for any damage you may encounter while using this program. I tried to remove all bugs and several people did some beta testing to find the rest. DISTRIBUTION: This program is SHAREWARE. You may test it over a period of 30 days. If you find it useful and like to use it regularly you must register. Otherwise you are using an illegal copy. It may (and should) be copied and distributed over BBS but no fees must apply and the package must stay complete. It may be compressed and/or encoded for transmission/storage purpose. Comercial PD/Shareware distributors may not take more than $3 as copy fee. REGISTRATION: The basic concept of SHAREWARE is to test the software if it suits your needs. If it does and you like to use it further, you must pay or you are using an illegal copy. The period of 30 days should be enough to decide if you like it or not. If you register, you will receive a key that removes the 10 file limit and the about box on exit. For more info about REGISTRATION read the file REGIST_E.TXT. 1. Overview 1.1. What is PICFIB? PICFIB stands for "PICture FIle Browser" and is a small utility that supports you in viewing a bunch of pictures. I got the idea for it one day when I got the ATARI GEMINI CD-ROM. It contained directories with dozens of IMG files (about 450). I viewed some and as I wanted to continue the next day I couldn't remember which I had already viewed. It was also a big mess to select FILE|OPEN before scrolling through the file list and select the next picture. To solve the problem I decided to write this utility. 1.2. What PICFIB does PICFIB allows you to create a list of pictures files by scanning through a specified directory. Each list entry has 4 tags assigned to the picture. Tag 1 is managed by the utility and stores information if this file has been viewed already. The other 3 tags are available to the user. You may set a filter and only view tagged (i.e. your favourite) pictures. Of course you can save and load the lists you created. PICFIB supports the following kinds of pictures: 2,4,16,256 colors/grays. You can view any picture in any resolution, but you will only see the most important planes of the picture if your resolution has less colors than required to view the picture. To improve the presentation of color/grayscale pictures in monochrome resolutions you can enable dithering using the Floyd/Steinberg method. 1.3 Hardware requirements PICFIB should run on any ST-Compatible computer in any palette based resolution (sorry, no True-Color support). 1.4 Limitation of PICFIB If you view pictures with more colors than your resolution supports the picture will be converted to a reduced color version. It depends on the video hardware if the result looks good or not. For photo realistic pictures you should use 256 colors. In the ST low resolution such pictures will look rather bad. Try to use the ST high resolution in these cases, because dithering will give better results. You can only load pictures that are smaller than 4096x4096 pixels and the available memory in your computer. 1.5 Supported graphic formats PICFIB supports the following formats: Extension Description IMG GEM IMG format (including XIMG) PC1,PC2,PC3 DEGAS uncompressed/compressed for all ST resolutions PCX ZSofts PC-Paintbrush format GIF CompuServe's Graphics Interchange Format TIFF Tagged Image File Format JPEG Joint Picture Experts Group file format Some notes on the TIFF format: The TIFF format was defined by Aldus and Microsoft and has been redefined at least once. It is very flexible and you can store additional information besides the picture. This flexibility has lead to the problem, that many TIFF files don't match the definition to 100%, because some programmers didn't follow the definition. So it has happened that a program couldn't read the TIFF files it has created. The TIFF library I used is very exact concerning this problem and refuses to load pictures with additional info that does not conform to the definition (picture data is not affected). This happened to me several times during the test phase. If it happens that a TIFF file is rejected by PICFIB you can only try to save this TIFF file with a second program hoping this creates valid files. Many thanks to Sam Leffler who has written this TIFF library and Dieter Linde who ported it to the Atari platform. See file TIFFCPRT.TXT for details. Some notes on the JPEG format: This library was also not written by myself and I would like to thank all members of the Independent JPEG Group who published their lib and made life so much easier for people like me. JPEG is rather complex format and it requires a lot of memory to decompress it. As a rough estimation you need about 10 bytes for each pixel in addition to the file itself and the image that is produced. So you would run out of memory very soon, but the members of the Independent JPEG Group added functions to allow swapping memory to disk and make a much wider range of pictures loadable. THIS FEATURE IS ALMOST NOT TESTED! I don't know what will happen on floppy only machines with little memory. 2. The Menus of PICFIB 2.1 The File menu 2.1.1 Create List.. Select this item to create a new picture file list. You will get the file selector where you should select the path where your pictures reside. The list will contain all files matching the entered extension. Depending on the option 'Scan through subdirs' only the selected directory or the whole directory tree will be searched. Tag 1 for all files will be checked and the Tool dialog will be opened. 2.1.2 Load List.. Select this item to load a previously stored list. The default extension for list files is 'TXT' since they are plain text files. The contents of the file will be broken into lines. The Tool dialog will be opened. Version 1.0a performs a security check to prevent accidential loading of text files that contain no PICFIB lists. When loading lists created with PICFIB V1.0 you will get a message box "PICFIB signature not found. Continue?". Answer "YES" to continue loading. Save the file again and the PICFIB signature will be included. 2.1.3 Save List.. Select this item to save the current list. The default extension for list files is 'TXT' since they are plain text files. The tags for each entry are also saved. 2.1.4 Export List.. This function allows you to create list files for use by other programs. First I'll present the export dialog and second I'll give you some examples how to use it. The export dialog contains a checkbox named "Include PICFIB header". Check this box if you plan to use the new list with PICFIB again. If you do so, you must enter exactly for character as a line prefix and leave the line suffix empty. Otherwise PICFIB will be in trouble when reading this list. If later versions of PICFIB should offer more tags you will have to enter an according number of characters. The next check box is named "Use filter options". Only if you check it, the other two radio buttons are used. If you use the "normal filter" you will get exactly those pictures that match the tags you checked in the options dialog (see section 2.1.5). Using the negated filter option creates a list containing all pictures that DON'T match the tags you checked. You may write some text into the edit fields below that is placed before/after each line of the saved list. Examples: (X) checked check box, (*) checked radio button ( ) unchecked check box/radio button 1.) How to create a new PICFIB list with all pictures that have tag 2 and tag 3 checked. All pictures of the new list should have tag 4 checked. -check tag 2 and tag 3 in the options dialog and choose "AND tags" -choose "Export List.." and set the following (X) Include PICFIB header (X) Use filter option (*) Normal filter ( ) Negated filter -at last enter " +" as line prefix (3 spaces, one plus char) -press OK and select/enter a filename in the file dialog. 2.) How to create a batch file to copy all pictures that have tag 2 or tag 4 checked to C:\PICS. -check tag 2 and tag 4 in the options dialog and choose "OR tags" -choose "Export List.." and set the following ( ) Include PICFIB header (X) Use filter option (*) Normal filter ( ) Negated filter -enter "copy " as line prefix and "C:\PICS" as line suffix -press OK and select/enter a filename with extension "BAT" in the file dialog. -Now you can start this batch in any shell and the files will be copied. 3.) How to create a batch file that deletes all files from C:\PICS that have neither tag 2 nor tag 4 checked. (List must be created for C:\PICS) -check tag 2 and tag 4 in the options dialog and choose "OR tags" -choose "Export List.." and set the following ( ) Include PICFIB header (X) Use filter option ( ) Normal filter (*) Negated filter -enter "del " as line prefix -press OK and select/enter a filename with extension "BAT" in the file dialog. -Now you can start this batch in any shell and the files will be deleted. If you are useng a UNIX compatible shell use UNIX specific commands instead (i.e."cp" and "rm"). 2.1.5 Options.. A dialog containing several check boxes appears. The first 4 check boxes corresponds with the tag numbers for each file. If you check one or more boxes you will only see pictures that have the appropiate tags checked. You can modify the filter with the option 'Match all tags' vs.'Match 1 tag'. 'Match all tags' means that the picture must have the same tags checked as are checked here. 'Match 1 tag' means that a picture must have at least one tag in common with the filter to be displayed. If you like to see all unseen pictures you only need to check tag 1 here. Below are two additional check boxes. 'Scan through subdirs' affects only the creation of new lists. Depending on this option only the selected directory or the whole directory tree will be searched. 'Dither pics if mono res' enables dithering in monochrome resolutions. This takes time of course, so don't worry if the busy bee remains on the screen, while the disc light is already off. If you have dithering disabled and are viewing color/grayscale pictures you will only see the most important plane. Sometimes you can get a first impression of the picture, but usually it won't look very good. 2.2 The View menu 2.2.1 First pic Select this item to load the first picture from file and display it in a window. This item is only available if you have created or loaded a list. Note that the filter options you set within the options dialog apply. So if you have set a filter and no file matches the filter you will get a message saying that the end of list was reached. 2.2.2 Next pic Select this item to load the next picture from file and display it. Filter options apply. 2.2.3 Prev pic Select this item to load the previous picture from file and display it. Filter options apply. 2.2.4 Jump to pic Select this item to jump to a specific picture. Enter the number you'd like to start viewing from. Filter options apply. 2.2.5 Single pic Select this item to load a single picture file and display it. It will not affect the picture list or other currently viewed pictures. 2.2.6 Tool dialog Select this item to open an additional window that offers more comfort in viewing the list and allows you to check/uncheck the tags for each file. The window has two buttons you can use to view the next/ previous file (the right button means the next file). Below you see four check boxes that reflect the current state of the tags for this file. You may check/uncheck them the way you like. Note that tag number 1 will be automatically unchecked if the file is viewed. For more info about filtering of tags refer to section 2.1.4. You can remove this window by selecting this item again. If the window is open the menu item is checked. 3. Keyboard usage Some functions are available exclusively or also via the keyboard -keys 1-4 toggle the state of corresponding tag for the current picture -use UNDO to toggle between the standard palette and the palette of the current picture. This is useful if you view a picture with many similar colors and you can't see the mouse or the menubar any more. 4. Miscellaneous PICFIB (the base program) was written with Turbo C 2.0 on a ATARI 260ST upgraded to 4MB and a Falcon030 in a period of about 8 weeks. The C source occupies about 150KB. It was tested with TOS 1.04, 2.06, TOS 4.04, MagiC! and in all resolutions a Falcon supports except 65536 color modes. Known Bugs: None found so far. Look at the file HISTORY.TXT to get more info about bugs being fixed in the current version. 4.1 The future of PICFIB If I get enough response I will definitely do further development on PICFIB like additional file formats (i.e BMP...) and a function to create a picture of thumbnails from a list of pictures. I'm also planning to make a version for Windows (currently in the works). 4.2 Bugs and features Proposals and error reports are always welcome. Error reports should include info about: - kind of computer ST/STE/TT/Falcon + hardware (Memory,CPU-Upgrades, enhanced graphic cards,...) - TOS version - TSR programs (TOSFIX,NVDI,GDOS,...) - Accessories - resolution used while the error occurred (colors, Pixels x*y) - Blitter activated? - Does the error occur repeatedly? - detailed info about the last user actions before the error occured - kind of error (redraw problem, bombs, ...) You find my address and how to contact me in REGIST_E.TXT.